home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / u_man / cat3 / Tcl / interp.z / interp
Encoding:
Text File  |  1998-10-30  |  7.8 KB  |  133 lines
  1.  
  2.  
  3.  
  4. TTTTccccllll____IIIInnnntttteeeerrrrpppp((((3333TTTTccccllll))))                                              TTTTccccllll____IIIInnnntttteeeerrrrpppp((((3333TTTTccccllll))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      Tcl_Interp - client-visible fields of interpreter structures
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      ####iiiinnnncccclllluuuuddddeeee <<<<ttttccccllll....hhhh>>>>
  13.  
  14.      typedef struct {
  15.           char *_r_e_s_u_l_t;
  16.           Tcl_FreeProc *_f_r_e_e_P_r_o_c;
  17.           int _e_r_r_o_r_L_i_n_e;
  18.      } Tcl_Interp;
  19.  
  20.      typedef void Tcl_FreeProc(char *_b_l_o_c_k_P_t_r);
  21.  
  22.  
  23. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  24.      The TTTTccccllll____CCCCrrrreeeeaaaatttteeeeIIIInnnntttteeeerrrrpppp procedure returns a pointer to a Tcl_Interp
  25.      structure.  This pointer is then passed into other Tcl procedures to
  26.      process commands in the interpreter and perform other operations on the
  27.      interpreter.  Interpreter structures contain many many fields that are
  28.      used by Tcl, but only three that may be accessed by clients:  _r_e_s_u_l_t,
  29.      _f_r_e_e_P_r_o_c, and _e_r_r_o_r_L_i_n_e.
  30.  
  31.      The _r_e_s_u_l_t and _f_r_e_e_P_r_o_c fields are used to return results or error
  32.      messages from commands.  This information is returned by command
  33.      procedures back to TTTTccccllll____EEEEvvvvaaaallll, and by TTTTccccllll____EEEEvvvvaaaallll back to its callers.  The
  34.      _r_e_s_u_l_t field points to the string that represents the result or error
  35.      message, and the _f_r_e_e_P_r_o_c field tells how to dispose of the storage for
  36.      the string when it isn't needed anymore.  The easiest way for command
  37.      procedures to manipulate these fields is to call procedures like
  38.      TTTTccccllll____SSSSeeeettttRRRReeeessssuuuulllltttt or TTTTccccllll____AAAAppppppppeeeennnnddddRRRReeeessssuuuulllltttt;  they will hide all the details of
  39.      managing the fields.  The description below is for those procedures that
  40.      manipulate the fields directly.
  41.  
  42.      Whenever a command procedure returns, it must ensure that the _r_e_s_u_l_t
  43.      field of its interpreter points to the string being returned by the
  44.      command.  The _r_e_s_u_l_t field must always point to a valid string.  If a
  45.      command wishes to return no result then _i_n_t_e_r_p->_r_e_s_u_l_t should point to an
  46.      empty string.  Normally, results are assumed to be statically allocated,
  47.      which means that the contents will not change before the next time
  48.      TTTTccccllll____EEEEvvvvaaaallll is called or some other command procedure is invoked.  In this
  49.      case, the _f_r_e_e_P_r_o_c field must be zero.  Alternatively, a command
  50.      procedure may dynamically allocate its return value (e.g. using mmmmaaaalllllllloooocccc)
  51.      and store a pointer to it in _i_n_t_e_r_p->_r_e_s_u_l_t.  In this case, the command
  52.      procedure must also set _i_n_t_e_r_p->_f_r_e_e_P_r_o_c to the address of a procedure
  53.      that can free the value (usually ffffrrrreeeeeeee).  If _i_n_t_e_r_p->_f_r_e_e_P_r_o_c is non-zero,
  54.      then Tcl will call _f_r_e_e_P_r_o_c to free the space pointed to by _i_n_t_e_r_p-
  55.      >_r_e_s_u_l_t before it invokes the next command.  If a client procedure
  56.      overwrites _i_n_t_e_r_p->_r_e_s_u_l_t when _i_n_t_e_r_p->_f_r_e_e_P_r_o_c is non-zero, then it is
  57.      responsible for calling _f_r_e_e_P_r_o_c to free the old _i_n_t_e_r_p->_r_e_s_u_l_t (the
  58.      TTTTccccllll____FFFFrrrreeeeeeeeRRRReeeessssuuuulllltttt macro should be used for this purpose).
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. TTTTccccllll____IIIInnnntttteeeerrrrpppp((((3333TTTTccccllll))))                                              TTTTccccllll____IIIInnnntttteeeerrrrpppp((((3333TTTTccccllll))))
  71.  
  72.  
  73.  
  74.      _F_r_e_e_P_r_o_c should have arguments and result that match the TTTTccccllll____FFFFrrrreeeeeeeePPPPrrrroooocccc
  75.      declaration above:  it receives a single argument which is a pointer to
  76.      the result value to free.  In most applications ffffrrrreeeeeeee is the only non-zero
  77.      value ever used for _f_r_e_e_P_r_o_c.  However, an application may store a
  78.      different procedure address in _f_r_e_e_P_r_o_c in order to use an alternate
  79.      memory allocator or in order to do other cleanup when the result memory
  80.      is freed.
  81.  
  82.      As part of processing each command, TTTTccccllll____EEEEvvvvaaaallll initializes _i_n_t_e_r_p->_r_e_s_u_l_t
  83.      and _i_n_t_e_r_p->_f_r_e_e_P_r_o_c just before calling the command procedure for the
  84.      command.  The _f_r_e_e_P_r_o_c field will be initialized to zero, and _i_n_t_e_r_p-
  85.      >_r_e_s_u_l_t will point to an empty string.  Commands that do not return any
  86.      value can simply leave the fields alone.  Furthermore, the empty string
  87.      pointed to by _r_e_s_u_l_t is actually part of an array of TTTTCCCCLLLL____RRRREEEESSSSUUUULLLLTTTT____SSSSIIIIZZZZEEEE
  88.      characters (approximately 200).  If a command wishes to return a short
  89.      string, it can simply copy it to the area pointed to by _i_n_t_e_r_p->_r_e_s_u_l_t.
  90.      Or, it can use the sprintf procedure to generate a short result string at
  91.      the location pointed to by _i_n_t_e_r_p->_r_e_s_u_l_t.
  92.  
  93.      It is a general convention in Tcl-based applications that the result of
  94.      an interpreter is normally in the initialized state described in the
  95.      previous paragraph.  Procedures that manipulate an interpreter's result
  96.      (e.g. by returning an error) will generally assume that the result has
  97.      been initialized when the procedure is called.  If such a procedure is to
  98.      be called after the result has been changed, then TTTTccccllll____RRRReeeesssseeeettttRRRReeeessssuuuulllltttt should
  99.      be called first to reset the result to its initialized state.
  100.  
  101.      The _e_r_r_o_r_L_i_n_e field is valid only after TTTTccccllll____EEEEvvvvaaaallll returns a TTTTCCCCLLLL____EEEERRRRRRRROOOORRRR
  102.      return code.  In this situation the _e_r_r_o_r_L_i_n_e field identifies the line
  103.      number of the command being executed when the error occurred.  The line
  104.      numbers are relative to the command being executed:  1 means the first
  105.      line of the command passed to TTTTccccllll____EEEEvvvvaaaallll, 2 means the second line, and so
  106.      on.  The _e_r_r_o_r_L_i_n_e field is typically used in conjunction with
  107.      TTTTccccllll____AAAAddddddddEEEErrrrrrrroooorrrrIIIInnnnffffoooo to report information about where an error occurred.
  108.      _E_r_r_o_r_L_i_n_e should not normally be modified except by TTTTccccllll____EEEEvvvvaaaallll.
  109.  
  110.  
  111. KKKKEEEEYYYYWWWWOOOORRRRDDDDSSSS
  112.      free, initialized, interpreter, malloc, result
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.